home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 351-375 / disk_368 / listwindow / readme < prev    next >
Text File  |  1992-05-06  |  3KB  |  64 lines
  1.                             ListWindow Package
  2.  
  3.                                 07/04/90
  4.                          (c) 1990 by Paul Miller
  5.  
  6.  
  7. The ListWindow Package (listwin_pak) is a useful package of simple functions
  8. for quick and easy programming of list window operations.
  9.  
  10. The package gives simple initialization, handling, and freeing of Macintosh-
  11. like "list-windows." These are user-sizeable windows with a scrollable list
  12. of text strings, optionally sortable. The list can be scrolled with a scroll-
  13. bar, up and down arrows, arrow keys, or a SHIFT+key combination which
  14. searches for the first occurance of the specified key in the name list, and
  15. sets the top of the list to that name (this is optional). All list-window
  16. control functions use a pointer to the window as a handle, so your program
  17. doesn't need to know anything about the internal manipulation of the lists.
  18. However, you can't use your Window->UserData pointer as the list-window
  19. package makes use of this.
  20.  
  21. This package is ideal for programs that display a list of commands, names,
  22. type sizes, fonts, etc, that need to be scrolled through, or can, optionally,
  23. be sized to the likes of the user. For example, If you are working on a ray-
  24. tracing program that has an indefinite number of available textures for
  25. mapping onto surfaces, you could make the list available within a list-window
  26. so the user can see as much of the list as he/she wants.
  27.  
  28. When a name is selected, the string is copied into an application-supplied
  29. buffer. The application program then uses this buffer to compare to its
  30. internal list of name strings. Since the list of names is sorted by the list-
  31. window package, returning the position of the name in the list may not have
  32. anything to do with the position of the name within the application. An array
  33. of pointers to text strings is used as the base of the list-window, kept
  34. within a NameList structure. The ListWindow Package also has functions used
  35. in allocating, copying, sorting, and freeing NameLists.
  36.  
  37. If a name is selected, and the list is scrolled, the "slot" that the name was
  38. in will remain hilighted and whatever name scrolls "under" the slot will be
  39. copied into the buffer and the application program will be notified of a name
  40. selection. This is provided in case you want "real-time" information update
  41. as the list is scrolled.
  42.  
  43. Note that I am NOT using Gadgets for name selections, but I am just reading
  44. mouse positions and decoding the slot position from that. After a long bit
  45. of frustration with dynamic allocation/deallocation of gadgets whenever the
  46. window is re-sized, I discovered that a bug in Intuition caused HUGE fragmen-
  47. tation when the window was sized smaller. All the memory was released, but
  48. the maximum available memory chunk was reduced to about 22K or less, which
  49. wasn't enough to even change the size of the window again. I think this
  50. boiled down to the RefreshGList() function and internal clip-rects and stuff.
  51. Anyway it's too much of a pain, so I use the simple old-fashioned (and
  52. less memory-hungry!) way.
  53.  
  54.  
  55. Don't forget to include the "listwin_pak.h" file in your programs.
  56.  
  57. Refer to "listwin_pak.doc" for more info.
  58.  
  59. See the included "Test" program for an example of setting up a ListWindow.
  60.  
  61. Feel free to use these functions or the object module in your programs. If
  62. you end up just linking in the listwin_pak.o object module, kindly mention
  63. me in your credits, eh? -Enjoy.
  64.